There are two animation arrays (one for human and one for horse). Each animation in these arrays contains the following fields:
1) Animation id (string): used for referencing animations in other files. The prefix anim_ is automatically added before each animation-id
2) Animation flags: could be anything beginning with acf_ defined in header_animations.py
3) Animation master flags: could be anything beginning with amf_ defined in header_animations.py
4) Animation sequences (list).
4.1) Duration of the sequence. Basically the speed of the animation, the higher the number, the slower the animation will progress.
4.2) Name of the animation resource.
4.3) Beginning frame of the sequence within the animation resource.
4.4) Ending frame of the sequence within the animation resource.
4.5) Sequence flags: could be anything beginning with arf_ defined in header_animations.py
4.6) Sound Timing (float): Optional. Used to play sounds in animations with arf_make_walk_sound and arf_make_custom_sound.
Can be used in conjunction with pack2f or pack4f to make the animation play the sound multiple times.
Timing assumed to be percentages ofanimation completion. For example a timing of 0.0 will play at the start while 1.0 will play at the end.
4.7) Offset Position (float, float, float): Optional. Used to move the animating agent's position at the end of the animation. Requires acf_displace_position flag.
4.8) Ragdoll Delay (float). Optional. Time, in seconds, for death animations to switch to ragdoll physics. Note, setting this for longer than 2.0 will cause the animation to hang instead of transitioning as the engine only tracks "dead" agents for this long before freezing them to free up resources.
module_animations.py is where the animation of the module are getting recorded and defined. The file has a declaration of constants before the usual list of tuples begins.
The animations are semi-hard-coded: Many animations are hard-coded such way inside the game engine that their position (if its #1, #100, etc.) matters. However, while the game engine expects animation #30 to do something when a particular action is used (like a block) you can still edit the individual sequences, resources or times and thus define your own visual animation and special flags. Important is that each animation must stay at the same position, otherwise the game won't run properly! You must not change the IDs of used animations![1]
To add an animation, you need to overwrite one of the "unused" animations.[2] Those are place holder animations and thus free, and can be used for stuff like a special animation for sitting, for a npc working on a field, etc. Stuff you will define by hand and for which you have a suitable animation resource at hand. Also keep in mind there are animation for humans and animations for horses, don't mix them. If the animation is for humans, you need to replace one of the anim_human_unused-lines and if it is for horses, replace one of the anim_horse_unused-lines. So comment out the first available "unused" animation and add or paste yours above or below it. You can also change the ID name of your animation to your likings.[3]
At adding new animations you need to provide a set of flags to control the execution, frames, speed, sync, if it should be on a cycle or not, the effect on rigging and how to blend in with the next animation.[4] Unfortunately the official documentation lacks details, so we try to fill out the gaps of knowledge about the meaning of some of the flags as good as we can.
The following animation capability flags are available for usage:[5]
| acf_align_with_ground | aligns the animation's up axis to the normal of the terrain below them for the duration of the animation. |
| acf_displace_position | is getting used in conjunction with tuple 4.7 to offset the agent at the end of the animation.[6] |
| acf_enforce_all | lets the animation play over all channels of the skeleton. |
| acf_enforce_lowerbody | lets the animation always play on the lower body channel, even if called to play on the upperbody. |
| acf_enforce_rightside | lets the animation fully take over the right skeletal mesh, with no blending from upper to lower body, or between animations. Rotates the right arm to the look direction (more than the rest of the upper body). |
| acf_ignore_slope | ignores the angle of the slope during the animation. |
| acf_left_cut | Up4research |
| acf_lock_camera | locks the camera angle in first person view with the current animation. |
| acf_overswing | Up4research |
| acf_parallels_for_look_slope | enables low and high angle versions for an animation. At the animation resource in the brf-file they should be put 100 frames before the normal animation for the low angle version, and 100 frames after for the high angle version.[7] |
| acf_right_cut | Up4research |
| acf_rot_vertical_bow | enables a vertical rotation to "aim" at the animation. |
| acf_rot_vertical_sword | enables a vertical rotation to "aim" at the animation which also affects the head and the right shoulder. |
| acf_rotate_body | a Vanilla M&B flag, it might work in the same way as acf_displace_position but for rotation? Up4research. |
| acf_synch_with_horse | synchronises the rider animation with that of their mount. |
| acf_thrust | Up4research |
The following animation master flags are available for usage:
| amf_accurate_body | Up4research |
| amf_client_owner_prediction | sends more precise animation info, like direction and frame to the server, for accurately combat calculations? Up4research. |
| amf_client_prediction | forces the animation to not sync with the server, or vise versa. Up4research. |
| amf_continue_to_next | plays sequencially the upfollowing animation when the current one has ended, regardless of its priority. |
| amf_hide_weapon | hides the weapon during the animation. |
| amf_keep | lets the animation hold at the last frame of the animation until an animation of equal or greater priority gets called. Using it together with arf_cyclic while having a variety of animation resources will probably let the agent stick to a specific randomly chosen animation until the agent switches to a different action, Up4research. |
| amf_play | lets the animation play through and end when reaching the final frame. |
| amf_restart | restarts the animation even if it is the current animation. |
| amf_rider_rot_bow | limits the rotation of the upper body of a mounted agent to a range from π rad, 180°, (rotation to the left) to -0.5 rad, -28.64°, (rotation to the right), in relation to the looking direction of the horse.[8] |
| amf_rider_rot_couched_lance | limits the rotation angle of the upper body of a mounted agent to a range from 0.75 rad, 42.97°, to -0.65 rad, -37.24°. |
| amf_rider_rot_crossbow | limits the rotation angle of the upper body of a mounted agent to a range from 2.5 rad, 143.24°, to -1.5 rad, -85.94°. |
| amf_rider_rot_defend | limits the rotation angle of the upper body of a mounted agent to a range from 2.0 rad, 114.59°, to -2.0 rad, -114.59°. |
| amf_rider_rot_overswing | limits the rotation angle of the upper body of a mounted agent to a range from 2.0 rad, 114.59°, to -2.0 rad, -114.59°. |
| amf_rider_rot_pistol | limits the rotation angle of the upper body of a mounted agent to a range from 1.0 rad, 57.30°, to -3.0 rad, -171.89°. |
| amf_rider_rot_shield | limits the rotation angle of the upper body of a mounted agent to a range from 3.0 rad, 171.89°, to -1.3 rad, -74.48°. |
| amf_rider_rot_swing_left | limits the rotation angle of the upper body of a mounted agent to a range from 2.0 rad, 114.59°, to -2.0 rad, -114.59°. |
| amf_rider_rot_swing_right | limits the rotation angle of the upper body of a mounted agent to a range from 2.0 rad, 114.59°, to -2.0 rad, -114.59°. |
| amf_rider_rot_throw | limits the rotation angle of the upper body of a mounted agent to a range from 2.8 rad, 160.43°, to -1.3 rad, -74.48°. |
| amf_rider_rot_thrust | limits the rotation angle of the upper body of a mounted agent to a range from 2.4 rad, 137.51°, to -1.5 rad, -85.94°. |
| amf_start_instantly | prevents that the animation needs to wait to start and interrupts all current animations to play. |
| amf_use_cycle_period | repeats the same animation if multiple animation resources are tied to a single action? Up4research. |
| amf_use_defend_speed | takes additionally the speed value of the currently wielded shield into account when calculating the duration of the animation. |
| amf_use_inertia | slows down the animation related to weapon mass? Apparently the animation will inherit the inertia from character movement to modify animation speeds Up4research. |
| amf_use_weapon_speed | takes additionally the speed value of the currently wielded weapon into account when calculating the duration of the animation. |
amf_client_prediction doesn't let animation sync, cmpxchg8b, Modding Q&A
amf_use_weapon_speed, Shredzorz (credit), [WB] Warband Script Enhancer v3.2.0}
custom mount animation and also some note about priority, The_dragon, Modding Q&A, and Modding Q&A
Animation Priority Flags are no genuine Animation Master Flags but custom declared flags. Animations can only play if they have a higher priority than the animation currently being played, i.e. Stand is a 0 priority animation, so every animation with a set priority can take priority, interrupt the animation and play. Alternatively, death has a priority of 95, so nothing can exceed this in Native.
amf_priority_jump = 2
amf_priority_ride = 2
amf_priority_continue = 1
amf_priority_attack = 10
amf_priority_cancel = 12
amf_priority_defend = 14
amf_priority_defend_parry = amf_priority_defend + 1
amf_priority_throw = amf_priority_defend + 1
amf_priority_blocked = amf_priority_defend_parry
amf_priority_parried = amf_priority_defend_parry
amf_priority_kick = 33
amf_priority_jump_end = 33
amf_priority_reload = 60
amf_priority_mount = 64
amf_priority_equip = 70
amf_priority_rear = 74
amf_priority_striked = 80
amf_priority_fall_from_horse = 81
amf_priority_die = 95
Take note that these are just values to orientate upon, you can declare your own flags or use plain numbers at the animation entries.
There is a different way to play an animation that does have lower priority using the flag amf_continue_to_next, where the animation immediately following the animation with that flag will play when the first animation ends. It can be assumed the follow up animation inherits the priority of the animation it is following as all native continue animations have a priority of 1.
The following animation sequence flags are available for usage:
| arf_blend_in_x | lets blend in an animation to the one currently playing. It is currently unknown if this is in frames, or some unknown measurement of time, Up4research. | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_cyclic | causes the animation sequence to loop, needs to be paired with amf_keep in order to function correctly. Constantly replaying an animation with arf_cyclic and missing amf_restart is a nice way to keep a loop going. | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_lancer | Up4research | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_make_custom_sound |
lets a sound be played when specific animations are getting triggered. The animations as well as the connected sounds are hardcoded, modders can basically just toggle the sound on or off by setting or removing this flag. The animation triggers and sound connections are as follows:
This flag is getting used together with the pack2f function in tuple 4.6. The first value of it determines at which percentage of the animation completion the first occasion sound (Get new ammo) is getting played, the second value determines the trigger moment of the second occasion sound (Reload ranged weapon) is getting played. The third occasion (Agent falling) has only one sound stage, so the second value is always zero. |
|||||||||||||||||||||||||||||||||||||||||||||||||
| arf_make_walk_sound | This flag is getting used together with the functions pack2f and pack4f after the arf-flags in the animation sequences. This are float checks for the animation progress and play on the respective occasions the footstep and jumping sounds for human and horse agents, also depending on if they are moving within the water or not. | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_use_stand_progress | lets the animation use the current stand animation progress. | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_stick_item_to_left_hand | sticks the weapon to the left hand during the animation. Mind that the weapon gets flipped when being put into the left hand. The mesh can additionally be offset (but not rotated) to let it fit better into the left hand. This offset can be influenced via the variables musket_left_hand_x/y/z_dif in the file game_variables.txt.[9] As the variable name indicates, this flag is usually getting used at loading animations of muskets. | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_two_handed_blade | Up4research | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_use_walk_progress | lets the animation use the current walk animation progress. | |||||||||||||||||||||||||||||||||||||||||||||||||
| arf_use_inv_walk_progress | same as arf_use_walk_progress, but plays the animation in reverse? Up4research. |
stick item to left hand animation problem, Somebody, Modding Q&A
arf left hand, Maxim Suvorov (credits?), Version 1.150 - 1.151 - 1.152 - 1.153 released
upper and lower body at animation, Example, Modding Q&A
uperbody part animation, jacobhinds, Modding Q&A
It is possible to add different variations of the same animation, just put them in the list of animation reference entries. If the animation has multiple parts and you have variations, they might however not sync up properly during the transitions.[10]
The settings pack2f and pack4f (pack two/four floats) are assigning sound to the animations, defining at what percentage of the animation a sound is getting played. The value are getting multiplied by 255 and then stored in 8 bits which means anything below 0 or over 1 will get clamped (0 = start of animation, 1 = end of animation). If more than two values are needed, pack4f is used instead of pack2f. How many and what sounds are actually played is almost entirely hardcoded,[11] see the descriptions of the animation sequence flags arf_make_custom_sound and arf_make_walk_sound for more details.
Entry field 4.8 contains the time, in seconds, for death animations to switch to ragdoll physics. Note, setting this for longer than 2.0 will cause the animation to hang instead of transitioning as the engine only tracks "dead" agents for this long before freezing them to free up resources. Mind that if a value below 0.01 is set, the game engine will use the value 0.5 instead. You can disable ragdolls at the Options in-game.[12]
Dead agents can still be affected by scripts for about 2 seconds after death, before they drop their weapons. You could use a shortened animation to get more interesting ragdolls, then, if the player is playing without ragdolls, continue on to play a different longer death animation instead. Unfortunately there's no operation to pull that particular setting, though, so you will have to create a trigger making use of ti_on_agent_killed_or_wounded.[13]
Unfortunately, specific movement or combat animations for custom races are not possible without extremely inefficient workarounds, i.e. working out when each animation would play (if the agent is further left than it was in the last frame, use the move left animation). It is made harder by the fact that for some silly reason animations have to be assigned at every frame, which also causes lag.[14]
Fun fact: After "researching" the engine it's quite obvious that the developers planned to have per-agent action sets but for some reason they scrapped the idea without even removing the code.[15]
The walking and holding animations are influenced by the item types of the weapons an agent is carrying and, to some lesser degree, by the item property and capability flags of the prementioned weapons. For this you will find first a description of each of the four cases and then, sorted by the cases, the animations connected to each case.
The connection between item flags and the running and walking animations is a simple one as can be seen in the table below. Take note that the * is replacing the direction of the animation, so backward, forward, left or right (or a combination of them like forward left etc.).[16]
| Case | Animation |
| Walking | |
| Case 0 | anim_walk_*, m_walkActionNo(?) |
| Case 1 | anim_walk_*_onehanded |
| Case 2 | anim_walk_*_staff and anim_walk_*_polearm |
| Case 3 | anim_walk_*_greatsword and anim_walk_*_twohanded |
| Common for all | anim_walk_*_hips_left/right |
| Running | |
| Case 0 | anim_run_* |
| Case 1 | anim_run_*_onehanded |
| Case 2 | anim_run_*_staff and anim_run_*_polearm |
| Case 3 | anim_run_*_greatsword and anim_run_*_twohanded |
| Common for all | anim_run_*_hips_left/right |
| Turning | |
| Case 0 | anim_turn_right/left |
| Case 1 | anim_turn_right/left_single |
| Case 2 | anim_turn_right/left_staff |
| Case 3 | anim_turn_right/left_greatsword |
The standing animations are also depending on the item types and item property flags as well as if the agent is idle or crouching:
| Case | Animation Condition |
| Case 0 | |
| IF Alarmed Agent OR Player in Battle OR mtf_team_fight OR Multiplayer | |
| Crouch | anim_crouch_unarmed |
| Idle | anim_stand_unarmed |
| Case 1 | |
| Crouch | anim_crouch_single |
| Idle | anim_stand_single |
| Case 2 | |
| IF itp_crossbow | |
| Crouch | anim_crouch_crossbow |
| Idle | anim_stand_crossbow |
| IF itp_is_pike AND turn amount < MAX(brace_rotation_limit; 0.01) | |
| Crouch | anim_crouch_pike |
| ELSE | |
| Crouch | anim_crouch_staff |
| Idle | anim_stand_staff |
| Case 3 | |
| Crouch | anim_crouch_greatsword |
| Idle | anim_stand_greatsword |
The engine is hard-coded to allocate only certain types of combat animations to items with certain item capability flags. You can always try combining existing animations to clear up slots or use up the sets that aren't in use in your module, like the pistol and musket animations in Native. Shield bash, horn blowing and other actions aren't weapon animations - they take up one of the unused human animation entries and are called on-demand by a trigger.[17]
The following tables list which animations are connected with which item capability flags, starting with the defending animations. Keep in mind that the animation entries can be named different than the animations inside the brf files. Do always look up the name of the animation resource at the tuple entry of the mentioned animation. Take note that the normal defending animations are getting overruled by the shield animations if the agent wears a shield, and are getting overruled by the fist defending animations if no weapons are given at all:
| itcf | Defend Action | Keep Action |
| Shield overrules | anim_defend_shield | anim_defend_shield_keep |
| Unarmed defense | anim_defend_fist | anim_defend_fist_keep |
If the agent has no shield the defending animations are as follows:
| itcf | Defend Action | Keep Action |
| Defend thrust | ||
| itcf_parry_forward_onehanded | anim_defend_forward_onehanded | ani_defend_forward_onehanded_keep |
| itcf_parry_forward_twohanded | anim_defend_forward_greatsword | anim_defend_forward_greatsword_keep |
| itcf_parry_forward_polearm | anim_defend_forward_staff | anim_defend_forward_staff_keep |
| Defend right | ||
| itcf_parry_right_onehanded | anim_defend_right_onehanded | anim_defend_right_onehanded_keep |
| itcf_parry_right_twohanded | anim_defend_right_twohanded | anim_defend_right_twohanded_keep |
| itcf_parry_right_polearm | anim_defend_right_staff | anim_defend_right_staff_keep |
| Defend left | ||
| itcf_parry_left_onehanded | anim_defend_left_onehanded | anim_defend_left_onehanded_keep |
| itcf_parry_left_twohanded | anim_defend_left_twohanded | anim_defend_left_twohanded_keep |
| itcf_parry_left_polearm | anim_defend_left_staff | anim_defend_left_staff_keep |
| Defend up | ||
| itcf_parry_up_onehanded | anim_defend_up_onehanded | anim_defend_up_onehanded_keep |
| itcf_parry_up_twohanded | anim_defend_up_twohanded | anim_defend_up_twohanded_keep |
| itcf_parry_up_polearm | anim_defend_up_staff | anim_defend_up_staff_keep |
For ranged weapons the itcf determine the ready and release animations as follows:[18]
| itcf | Ready Action | Release Action |
| itcf_shoot_bow | anim_ready_bow | anim_release_bow |
| itcf_shoot_crossbow | anim_ready_crossbow | anim_release_crossbow |
| itcf_shoot_pistol if crouching |
anim_ready_pistol anim_crouch_ready_pistol |
anim_release_pistol anim_crouch_release_pistol |
| itcf_shoot_musket | anim_ready_musket | anim_release_musket |
| itcf_throw_stone | anim_ready_stone | anim_release_stone |
| itcf_throw_knife | anim_ready_throwing_knife | anim_release_throwing_knife |
| itcf_throw_axe | anim_ready_throwing_axe | anim_release_throwing_axe |
| itcf_throw_javelin | anim_ready_javelin | anim_release_javelin |
Crossbows, muskets and pistols are the only ranged items which have a separate reloading animation, at the others it is integrated at the ready action. If use_phased_reload is set to 1 in module.ini, the reloading of muskets and guns can get done with intermediate steps.
| itcf | Reload Action | |
| itcf_shoot_crossbow if mounted and no itp_cant_reload_on_horseback is set |
anim_reload_crossbow anim_reload_crossbow_horseback |
|
| itcf_reload_pistol if 'use_phased_reload = 1' is set and reload has been interrupted at middle |
anim_reload_pistol anim_reload_pistol_half |
|
| itcf_reload_musket if 'use_phased_reload = 1' is set and reload has been interrupted |
anim_reload_musket anim_reload_musket_full |
|
For close combat weapons the itcf determines the ready and release animations for unmounted agents as follows (Pay attention to the different conditions alongside the itcf!):
| itcf and condition | Ready Action | Release Action |
| Thrust | ||
| itcf_thrust_twohanded AND no shield | anim_ready_thrust_twohanded | anim_release_thrust_twohanded |
| itcf_thrust_polearm AND no shield | anim_ready_thrust_staff | anim_release_thrust_staff |
| itcf_thrust_onehanded AND (shield OR no itcf_thrust_polearm) | anim_ready_thrust_onehanded | anim_release_thrust_onehanded |
| itcf_thrust_onehanded_lance AND (shield OR no itcf_thrust_polearm) | anim_ready_thrust_onehanded_lance | anim_release_thrust_onehanded_lance |
| itcf_thrust_musket AND (shield OR no itcf_thrust_polearm) | anim_ready_thrust_musket | anim_release_thrust_musket |
| Overswing | ||
| itcf_overswing_twohanded AND no shield | anim_ready_overswing_twohanded | anim_release_overswing_twohanded |
| itcf_overswing_polearm AND no shield | anim_ready_overswing_staff | anim_release_overswing_staff |
| itcf_overswing_onehanded | anim_ready_overswing_onehanded | anim_release_overswing_onehanded |
| itcf_overswing_spear AND no shield | anim_ready_overswing_spear | anim_release_overswing_spear |
| itcf_overswing_musket AND (shield OR no itcf_overswing_polearm) | anim_ready_overswing_musket | anim_release_overswing_musket |
| Swing left | ||
| itcf_slashleft_twohanded AND no shield | anim_ready_slashleft_twohanded | anim_release_slashleft_twohanded |
| itcf_slashleft_polearm AND no shield | anim_ready_slashleft_staff | anim_release_slashleft_staff |
| itcf_slashleft_onehanded | anim_ready_slashleft_onehanded | anim_release_slashleft_onehanded |
| Swing right | ||
| itcf_slashright_twohanded AND no shield | anim_ready_slashright_twohanded | anim_release_slashright_twohanded |
| itcf_slashright_polearm AND no shield | anim_ready_slashright_staff | anim_release_slashright_staff |
| itcf_slashright_onehanded | anim_ready_slashright_onehanded | anim_release_slashright_onehanded |
For mounted agents the ready and release animations are as follows:
| itcf and condition | Ready Action | Release Action |
| Thrust | ||
| itcf_thrust_onehanded | anim_ready_thrust_onehanded_horseback | anim_release_thrust_onehanded_horseback |
| itcf_thrust_onehanded_lance | anim_ready_thrust_onehanded_lance | anim_release_thrust_onehanded_lance |
| Overswing | ||
| itcf_overswing_onehanded | anim_ready_overswing_onehanded | anim_release_overswing_onehanded |
| Swing left | ||
| itcf_horseback_slashleft_onehanded AND itcf_horseback_slash_polearm | anim_ready_slash_horseback_polearm_left | anim_release_slash_horseback_polearm_left |
| itcf_horseback_slashleft_onehanded | anim_ready_slash_horseback_left | anim_release_slash_horseback_left |
| Swing right | ||
| itcf_horseback_slashright_onehanded AND itcf_horseback_slash_polearm | anim_ready_slash_horseback_polearm_right | anim_release_slash_horseback_polearm_right |
| itcf_horseback_slashright_onehanded | anim_ready_slash_horseback_right | anim_release_slash_horseback_right |
Parry animations are still missing
Changing blocking speed, Somebody, Modding Q&A
unequip animations would be interesting to know the relation/connection to flags, to do
phased reload, Slawomir of Aaarrghh, Version 1.150 - 1.151 - 1.152 - 1.153 released
Creating animation test, xenoargh, Modding Q&A
set animation in mp, Vornne and MadocComadrin, Modding Q&A
agent set animation for horse, Somebody, Modding Q&A
Some jumping animation info, Lumos, Modding Q&A
knockdown animation, _Sebastian_, Modding Q&A
stop cyclic animation, _Sebastian_, Modding Q&A
kill player at certain frame of animation, The_dragon, Modding Q&A
it is possible to use an engine trick in WB to shoot a pistol through a shield, using a custom animation, Darth Mongol the Unwise, Mount & Blade Modding Discord